
    	COM-Poisson Code Function Summary
	   
	  Author: Daniel Durnford (d.durnford@queensu.ca)
	  Last Updated: October 26th 2018

-------------------------------------------------------------------------------------------

This document is intended to provide a brief summary of the different functions contained 
in the COM-Poisson code provided "COMPoisson.cc". All the code described here is the first 
version made available. If updates are made in the future, a document recording version
history will be made. The functions are divided into two categories: "primary", which are 
directly useful, and "secondary", which are mostly called by primary functions.

================================     Primary Functions     ================================

BuildCOM: 
This function builds a probability distribution function for a given mean and Fano factor. 
This is done with the COM-Poisson distribution (using look-up tables or asymptotic 
expression), Poisson distribution, Gaussian distribution, or Bernoulli distribution when 
appropriate. The final output of the function is the cumulative distribution function 
stored in a global std::vector "cdf", the moments of the distribution are stored globally 
in the variables "G_mu" and "G_var", and the COM-Poisson parameters are stored globally 
in "G_l", and G_v" if appropriate. The criteria for using each distribution can be 
summarized as:

		-> If F = 1, the Poisson distribution is used.
		-> If mu > G_Transition, a Gaussian distribution is used ("G_Transition" is 
			the globally-set value of mu that defines this choice).
		-> If the desired (mu,F) is within 0.1% of the Bernoulli modes, the Bernoulli
			distribution is used, as determined with the function isSoft().
		-> If mu > 20, and the above conditions are not true, the COM-Poisson distribution 
			is used with the asymptotic expressions.
		-> If mu < 20 and the first three criteria are not true, the appropriate lambda 
			and nu are retrieved from the look-up tables and bi-linear interpolation if 			
			needed. The total error obtained with these values is compared with the total 
			error from the asymptotic approximations for lambda and nu, and the more 				
			accurate is chosen.

If the error in mu or F obtained (with COM-Poisson) is greater than 0.1%, the function 
Zombie_Fix() is used to find the correct lambda and nu. This is very rarely necessary. 
After all of this the CDF is built and moments calculated by the appropriate methods, and 
if the print-out option is true, a report of the results is printed.
___________________________________________________________________________________________

BuildCOM_Fast: 
This function has the same purpose as BuildCOM() but is meant to be faster (although 
possibly less accurate) by omitting several checks and functionalities performed by 
BuildCOM(). Specifically, it doesn't compare the asymptotic expressions and look-up tables, 
consider Zombie_Fix(), calculate the error in mu and F, or print a report.
___________________________________________________________________________________________

P_COM: 
Essentially the same functionality as BuildCOM() and BuildCOM_Fast() except instead of 
building a cdf it returns the probability of having X with the defined distribution, so 
P(X|mu,F).
___________________________________________________________________________________________

PCOM_Fast: 
This function is a faster version of PCOM() but that, similarly to BuildCOM_Fast(), skips 
some checks and functionality to reduce computation time.
___________________________________________________________________________________________

BuildHisto: 
Simple function to generate histogram of random numbers obtained using cdfDraw. BuilCOM() 
or BuildCOM_Fast() must be called first to define the CDF from which numbers are drawn.
___________________________________________________________________________________________

cdfDraw: 
Function to return a random number (non-negative integers) from the globally defined CDF 
(cumulative distribution function) "cdf". Hence, BuildCOM() or BuildCOM_Fast() must be used 
FIRST to build the CDF.
___________________________________________________________________________________________

TableReader: 
Function to load the files of the look-up tables. The name, directory, and definition of 
the tables is set globally. The tables are stored in global arrays "L_Table" and "V_Table". 
The values of lambda/nu for all values of mean within the tables and values of F that are 
multiples of 0.1 are stored in the TGraphs "l_single" and "v_single" to increase 
computational efficiency. This is done because a 1D interpolation handled by ROOT is faster 
than the home-made interpolation code BiTerp().

==============================     Secondary Functions     =============================== 

linspace: 
Calculates linearly spaced values.
___________________________________________________________________________________________

logspace: 
Calculates logarithmically (base 10) spaced values.
___________________________________________________________________________________________

Moments: 
Function to calculate the mean and variance obtained for given lambda and nu, using infnite 
sum formulas, calculated in a while-loop. Convergence condition is based on tolerance set 
manually in the function. There are also fail-safe options to exit the while-loops. It also 
uses Stirling's approximation when needed. The results are stored globally as "G_mu" and 
G_var".
___________________________________________________________________________________________

Z: 
Function to calculate the normalizing constant Z of the COM-Poisson distribution, using a 
while-loop. Convergence condition is based on tolerance set in function. There is also a 
fail-safe option to exit the while-loop, and a condition to use Stirling's approximation 
when needed.
___________________________________________________________________________________________

Z_asymp: 
Function to calculate the log of Z directly using the asymptotic expression for Z.
___________________________________________________________________________________________
 
logZ: 
Function to calculate the log of Z directly, trying to use "Z" first but then using 
"Z_asymp" if Z == inf.
___________________________________________________________________________________________

COM: 
Actual implementation of the COM-Poisson PDF, structured such that it can be used to create 
a TF1. Uses Stirling's approximation when appropriate.
___________________________________________________________________________________________

cdfBuild: 
Constructs CDF (and PDF) for the COM-Poisson distribution using the TF1 for the COM-Poisson 
distribution. The start and end points of the CDF/PDF (cdf_a and cdf_b) are set globally. 
The CDF and PDF are stored globally in std vectors.
___________________________________________________________________________________________

cdfBuild_FAST: 
Constructs CDF (and PDF) for the COM-Poisson distribution using the iterative method. The 
start and end points of the CDF/PDF (cdf_a and cdf_b) are set globally. The CDF and PDF are 
stored globally in std vectors. This is computationally faster.
___________________________________________________________________________________________

Zombie_Fix: 
This code is used in cases where the look-up tables/interpolation are insufficiently 
accurate, or when greater accuracy is desired. It uses a sort of "random walk" approach to 
find the lambda and nu needed for a desired mu and F, to a given precision. It has an 
option for printing out it's results, and will exit automatically if it exceeds the given 
number of iterations without converging. It may be called by BuildCOM() or PCOM(), but 
very, very rarely.
___________________________________________________________________________________________

Stirling: 
Implementation of Stirling's approximation.
___________________________________________________________________________________________

isBernoulli:
Function that returns whether or not given values of mean/F are within the Bernoulli modes 
(true or false).
___________________________________________________________________________________________

isSoft: 
Function that returns whether or not given values of mean/F are within the given distance 
of the Bernoulli modes (true or false). Hence isBernoulli == true implies isSoft == true, 
but not vice versa.
___________________________________________________________________________________________

BiTerp: 
Function to implement simple bilinear interpolation of look-up tables. For given desired 
values of mu/F, it scans through the tables to find the four points of mu/F closest to the 
desired values, and then performs a simple interpolation of the look-up tables to give 
values of lambda and nu.
___________________________________________________________________________________________

cdfBernoulli: 
A function that constructs a CDF using the Bernoulli distribution, stored globally in the 
std::vector "CDF".
___________________________________________________________________________________________

cdfGauss: 
Function that constructs a CDF (and PDF) using a Gaussian distribution, stored globally in 
the std::vectors "CDF" and "PDF" respectively.
___________________________________________________________________________________________

Bernoulli: 
Function that returns the variance of the Bernoulli mode, as a function of mu.
___________________________________________________________________________________________

LV_asymp: 
Function that gives asymptotic approximations for lambda and nu, which are stored globally 
as "l_asymp" and "v_asymp".
___________________________________________________________________________________________

pdfBernoulli: 
Function that returns the probability P(X|mu) for the Bernoulli distribution.
___________________________________________________________________________________________

Gerror: 
This function runs Moments() for the given lambda and nu, and calculates the error in mu, 
variance, and F, which are stored globally in "G_mu_e", "G_var_e", and "G_F_e" respectively.
___________________________________________________________________________________________

BinLogX: 
Simple function to create logarithmic histogram bins.
___________________________________________________________________________________________
